The Results Manager

If an application needs to do more than simply export text to a searchable text or PDF document, then the Internal Structured Data generated by a OCRX_recognize_to_memory() process can be accessed via a set of “Get” functions. The Get functions, as a whole, are referred to as the Results Manager.

In order to use the Results Manager, it is beneficial to understand the relationship between the different layers of the Internal Structured Data. (See figures 1 and 2 in OCR Xpress for Linux Functionality)

• The top most layer is called the document. A document is a set of one or more pages.

• Each page is the captured results of a single image. Each page is broken down into one or more Regions.

• The regions may be segmented along a number of parameters.
  For example, the character height of all the characters in one region may be different than the height of the characters in another region. In this case, the two regions were segmented by the character height parameter.
  In most cases, there will only be one region per page. Each Region is broken down into Text Blocks (usually paragraphs).
  Note that for Regions and Text Blocks there are no hard rules for segmenting them. There are many elements of an image that can affect how the two layers get segmented. Their primary use is for generalized segmentation or grouping of the more important sub-layers; Text Lines, Words, and Characters.

• Each Text Block will contain one or more Text Lines.
• Each Text Line will contain one or more Words.
• Each Word will contain one or more Characters.

The Results Manager allows applications to transverse the layers of the Internal Structured Data in a coherent manner. In short, applications can interrogate every item in every sub-layer of a page, every item in every sub-layer of a text block, and so on. Every item can be interrogated for its content, its position in the image, or even the confidence that the OCR result is correct.

The term result element is used to refer to any document, page, region, text block, text line, word, or character.

The terms ancestor and descendant are used in lieu of parent and child to indicate that multiple levels of the hierarchy can be crossed in a single step. For example, you can get a word directly from a page without needing to traverse the region, text block, and text line in between.

The Get Functions

The Results Manager is a collection of Get functions.

The most important and most complex Get function is OCRX_get_descendant_result(). With this function, applications can get a handle to any descendant element of a given result element.

// Get a handle to the fourth word in a given region. 
OCRX_Result word = 0; // When OCRX_get_descendant_result() returns, this
                      // will be a handle to the fourth word.
OCRX_get_descendant_result(
            region,               // Handle to the region.
            OCRX_ResultType_Word, // Specifies that we want a word from the region.
            3,                    // Zero-based index of the word we want.
            &word);               // Output parameter for the word handle.

Applications can get any ancestor element of a given result element using the OCRX_get_ancestor_result() function.

// From a given character handle, get a handle to the text line that contains the character.
OCRX_Result line = 0;  // When OCRX_get_ancestor_result() returns, this
                   // will be a handle to the text line containing the character.
OCRX_get_ancestor_result(
            character,                // Handle to the character.
            OCRX_ResultType_TextLine, // Specifies that we want the containing text line.
            &line );            // Output parameter for the text line handle.

Once the handle to an element has been acquired, the other Get functions in the Results Manager are used to retrieve data from that element:

• OCRX_get_utf8_text_size()
• OCRX_get_utf8_text()

In order to copy text out of OCR Xpress for Linux, the application has to allocate a buffer to hold the text. The application will call OCRX_get_utf8_text_size() to determine how large of a buffer to allocate. It will then call OCRX_get_utf8_text() to copy the text into the allocated buffer.

In the following example code, the handle to the element containing the text to be copied is labeled “result” in the argument list.

// Determine the required buffer size. 
int32_t bufferSize;
OCRX_get_utf8_text_size(result, &bufferSize);
// Allocate the buffer.
char* buffer = (char*)malloc(bufferSize);  
// Copy the text into the buffer.
OCRX_get_utf8_text(result, buffer, bufferSize);
// Do something with the text.
free(buffer);

OCRX_get_area()

Gets the area, in pixel units, of a given result element.

OCRX_Rectangle area = {0, 0, 0, 0};
OCRX_get_area(result, &area);

OCRX_get_confidence()

Get's the confidence of a given result element.

int32_t confidence = 0;
OCRX_get_confidence(result, &confidence);

OCRX_get_orientation()

Gets the orientation of the result element.

int32_t orientation = 0;
OCRX_get_orientation(result, &orientation);

OCRX_get_result_type()

Gets the type of a given result element.

OCRX_ResultType elementType = OCRX_ResultType_Document;
OCRX_get_result_type(result, &elementType);